<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita>
  <topic id="topic_fstrm">
    <title>advanced_password_check</title>
    <body>
      <p>The <codeph>advanced_password_check</codeph> module provides password
        quality checking for Greenplum Database.</p>
      <p>The Greenplum Database <codeph>advanced_password_check</codeph> module
        is based on the <codeph>passwordcheck_extra</codeph> module, which
        enhances the PostgreSQL <codeph>passwordcheck</codeph> module to
        support user-defined policies to strengthen
        <codeph>passwordcheck</codeph>'s minimum password requirements.</p>
    </body>
    <topic id="topic_reg">
      <title>Loading the Module</title>
      <body>
        <p>The <codeph>advanced_password_check</codeph> module provides no
          SQL-accessible functions. To use it, simply load it into the server.
          You can load it into an individual session by entering this command as
          a superuser:<codeblock># LOAD 'advanced_password_check';</codeblock></p>
        <p>More typical usage is to preload it into all sessions by including
          <codeph>advanced_password_check</codeph> in 
          <codeph>shared_preload_libraries</codeph> in <codeph>postgresql.conf</codeph>:
          <codeblock>shared_preload_libraries = '<i>other_libraries</i>,advanced_password_check'
</codeblock>
          and then restarting the Greenplum Database server.</p>
      </body>
    </topic>
    <topic id="topic_using">
      <title>Using the advanced_password_check Module</title>
      <body>
        <p><codeph>advanced_password_check</codeph> is a Greenplum Database module
          that you can enable and configure to check password strings against
          one or more user-defined policies. You can configure policies that:
          <ul>
            <li>Set a minimum password string length.</li>
            <li>Set a maximum password string length.</li>
            <li>Define a custom list of special characters.</li>
            <li>Define rules for special character, upper/lower case character,
              and number inclusion in the password string.</li>
          </ul>
        </p>
        <p>The <codeph>advanced_password_check</codeph> module defines server
          configuration parameters that you set to configure password setting
          policies. These parameters include:</p>
        <table>
          <title>Configuration Parameters</title>
          <tgroup cols="4">
            <colspec colnum="1" colname="col1" colwidth="75pt"/>
            <colspec colnum="2" colname="col2" colwidth="29pt"/>
            <colspec colnum="3" colname="col3" colwidth="29pt"/>
            <colspec colnum="4" colname="col4" colwidth="159pt"/>
            <thead>
              <row>
                <entry colname="col1">Parameter Name</entry>
                <entry colname="col2">Type</entry>
                <entry colname="col2">Default Value</entry>
                <entry colname="col2">Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry colname="col1">minimum_length</entry>
                <entry colname="col2">int</entry>
                <entry colname="col3">8</entry>
                <entry colname="col4">The minimum allowable length of a Greenplum
                  Database password.</entry>
              </row>
              <row>
                <entry colname="col1">maxmum_length</entry>
                <entry colname="col2">int</entry>
                <entry colname="col3">15</entry>
                <entry colname="col4">The maximum allowable length of Greenplum
                  Database password.</entry>
              </row>
              <row>
                <entry colname="col1">special_chars</entry>
                <entry colname="col2">string</entry>
                <entry colname="col3">!@#$%^&#x26;*()_+{}|&lt;>?=</entry>
                <entry colname="col4">The set of characters that Greenplum
                  Database considers to be special characters in a password.</entry>
              </row>
              <row>
                <entry colname="col1">restrict_upper</entry>
                <entry colname="col2">bool</entry>
                <entry colname="col3">true</entry>
                <entry colname="col4">Specifies whether or not the password
                  string must contain at least one upper case character.</entry>
              </row>
              <row>
                <entry colname="col1">restrict_lower</entry>
                <entry colname="col2">bool</entry>
                <entry colname="col3">true</entry>
                <entry colname="col4">Specifies whether or not the password
                  string must contain at least one lower case character.</entry>
              </row>
              <row>
                <entry colname="col1">restrict_numbers</entry>
                <entry colname="col2">bool</entry>
                <entry colname="col3">true</entry>
                <entry colname="col4">Specifies whether or not the password
                  string must contain at least one number.</entry>
              </row>
              <row>
                <entry colname="col1">restrict_special</entry>
                <entry colname="col2">bool</entry>
                <entry colname="col3">true</entry>
                <entry colname="col4">Specifies whether or not the password
                  string must contain at least one special character.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <p>After you define your password policies, you run the
          <codeph>gpconfig</codeph> command for each configuration parameter
          that you must set. When you run the command, you must qualify the
          parameter with the module name. For example, to configure Greenplum
          Database to remove any requirements for a lower case letter in the
          password string, you run the following command:</p>
        <codeblock>gpadmin@gpmaster$ gpconfig -c advanced_password_check.restrict_lower -v false</codeblock>
        <p>After you set or change module configuration in this manner, you
          must reload the Greenplum Database configuration:</p>
        <codeblock>gpadmin@gpmaster$ gpstop -u</codeblock>
      </body>
    </topic>
    <topic id="topic_example">
      <title>Example</title>
      <body>
        <p>Suppose that you have defined the following password policies:</p>
        <ul>
          <li>The password must contain a minimum of 10 characters and a maximum
            of 18.</li>
          <li>The password must contain a mixture of upper case and lower case
            characters.</li>
          <li>The password must contain at least one of the default special
             characters.</li>
          <li>The are no requirements that the password contain a number.</li>
        </ul>
        <p>You would run the following commands to configure Greenplum Database
          to enforce these policies:</p>
      <codeblock>
gpadmin@gpmaster$ gpconfig -c advanced_password_check.minimum_length -v 10
gpadmin@gpmaster$ gpconfig -c advanced_password_check.maximum_length -v 18
gpadmin@gpmaster$ gpconfig -c advanced_password_check.restrict_number -v false
gpadmin@gpmaster$ gpstop -u</codeblock> 
      <p>After loading the new configuration, passwords that the Greenplum
        superuser sets must now follow the policies, and Greenplum returns an
        error for every policy that is not met. Note that Greenplum checks the
        password string against all of the policies, and concatenates together
        the messages for any errors that it encounters.
        For example (line breaks added for better viewability):</p>
      <codeblock># testdb=# CREATE role r1 PASSWORD '12345678901112';
ERROR:  Incorrect password format: lower-case character missing, upper-case character
missing, special character missing (needs to be one listed in "&lt;list-of-special-chars>")</codeblock>
      </body>
    </topic>
    <topic id="topic_info">
    <title>Additional Module Documentation</title>
      <body>
        <p>Refer to the <xref href="https://www.postgresql.org/docs/9.4/passwordcheck.html"
          format="html" scope="external">passwordcheck</xref> PostgreSQL documentation for
          more information about this module.</p>
      </body>
    </topic>
  </topic>
</dita>
